home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1992 June: ROMin Holiday / ADC Developer CD (1992-06) (''ROMin Holiday'')_iso / Developer Connection - 06-1992.iso / Developer Essentials / DTS Sample Code / System 7.0 Samples / MacShell / !!! how.to.do.it < prev    next >
Encoding:
Text File  |  1991-12-04  |  7.7 KB  |  182 lines  |  [TEXT/MPS ]
  1. MacShell was written as an application shell to simplify getting a
  2. Macintosh application started.  There is a large amount of code that
  3. a developer needs to write for a Macintosh application before
  4. even getting to the interesting stuff.  MacShell is an attempt at
  5. reducing this initial coding effort.
  6.  
  7. With 7.0 now upon us, this initial effort has grown.  There are a number
  8. of new things that an application has to do in order to be 7.0 savvy.
  9.  
  10. MacShell attempts to remove this burden from the developer by implementing
  11. the basics as completely as possible.  The basics include the File and
  12. Edit menus, plus handling windows, printing, code for AppleEvente, etc.
  13.  
  14. To implement the File and Edit menus, MacShell must know something about
  15. your document.  If it didn't, menu items like printing wouldn't be able
  16. to be implemented for you.
  17.  
  18. MacShell doesn't need to know much about the document or its structure.
  19. Most of what it needs to know about is outlined in the below structure:
  20.  
  21.  
  22. typedef struct {
  23.     OSType                    sfType;
  24.     Boolean                    docDirty;
  25.     Boolean                    readOnly;
  26.     short                    refNum;
  27.     FSSpec                    fss;
  28.     WindowPtr                window;
  29.     ImageProcPtr            imageProc;
  30.     ContentClickProcPtr        contentClickProc;
  31.     ContentKeyProcPtr        contentKeyProc;
  32.     InitContentProcPtr        initContentProc;
  33.     ResizeContentProcPtr    resizeContentProc;
  34.     DrawFrameProcPtr        drawFrameProc;
  35.     CalcFrameRgnProcPtr        calcFrameRgnProc;
  36.     short                    attributes;
  37.     ControlHandle            hScroll;
  38.     ControlHandle            vScroll;
  39.     short                    hArrowVal;
  40.     short                    vArrowVal;
  41.     short                    hPageVal;
  42.     short                    vPageVal;
  43.     short                    hDocSize;
  44.     short                    vDocSize;
  45. } FileStateRec;
  46.  
  47.  
  48. It needs to know if the  document is dirty (has changed) so that it
  49. knows whether or not to put up a dialog when the user tries to close
  50. the window.  It also needs to know if the user opened the document
  51. as a read-only document.  (This can occur if you are opening a file
  52. over a network that has already been opened by another user.)  It needs
  53. the file reference number and file specification (yawn).  It needs to 
  54. know the procedure you wish to use to update the window content and
  55. print.  It needs to know what procedure you wish to use to initialize
  56. the content of the window.  (Content initialization may mean adding
  57. controls to the content, for example.)  If your window has document
  58. scrollbars, it needs to know how far to scroll for the line, and page
  59. parts of the control.  It needs to know how big the document is.
  60.  
  61. The fields from docDirty through calcFrameRgnProc are all initialized
  62. for you.  These pertain to the document.  The rest of the fields are
  63. not initialized until you create a window for the document.  A document
  64. is first created without a window, and then you can give the document
  65. a window, if you wish.  (A document that is only printed doesn't need
  66. a window, since it never becomes visible.)
  67.  
  68. If you choose to give the document a window, you call DoNewWindow.
  69. DoNewWindow creates a window for the document passed it.  If the
  70. window is successfully created, DoNewWindow then calls the procedure
  71. indicated by the field initContentProc.  The default procedure is
  72. called InitContent, and unless you change it, this is what
  73. the field initContentProc holds.
  74.  
  75. MacShell already is coded up to do this.  If the user selects New or Open
  76. from the File menu, AppNewDocument or AppOpenDocument is first called.
  77. If that succeeds, DoNewWindow is called for that document.  If that
  78. succeeds, the window then becomes visible for the user.
  79.  
  80. The content of the window is drawn by the procedure pointed to by the
  81. field imageProc.  The field imageProc is initialized to point to the
  82. procedure ImageDocument.  This procedure pointer is used whenever the
  83. window needs updating or whenever the document needs printing.  Just
  84. as you can override the initContentProc, you can override the imageProc
  85. by changing it after creating the document and prior to calling
  86. DoNewWindow.  This allows you to have more than one document type for
  87. your application.
  88.  
  89.  
  90. The part that you need to do for file I/O is to replace the following
  91. functions in file2.c:
  92.  
  93.     AppFreeDocument();
  94.     AppInitDocument();
  95.     AppReadDocument();
  96.     AppWriteDocument();
  97.     AppDuplicateDocument();
  98.  
  99. AppInitDocument is called by AppNewDocument.  The default initialization
  100. has already been done.  There may be more that you need to do for your
  101. document architecture.  Your document may be a single big handle.  If
  102. so, then AppInitDocument needs to create this handle.  If you can't
  103. create it, then you need to return the appropriate error so that
  104. AppNewDocument knows that it failed.
  105.  
  106. AppReadDocument is called by AppOpenDocument.  AppOpenDocument first
  107. calls AppNewDocument to create a new document.  If it succeeds, it
  108. then calls AppNewDocument to create a new empty document.  If this
  109. succeeds, it then calls AppReadDocument.  AppReadDocument is your
  110. code.  You write the code that actually reads in the data.  You read
  111. the data into the document structure.  This structure is defined
  112. as follows:
  113.  
  114.  
  115. typedef struct {
  116.     short            version;            /* The file format version.                        */
  117.     Boolean            printRecValid;        /* True if print record has been created.        */
  118.     TPrint            print;                /* Print record for file.                        */
  119.     short            endVersPrintInfo;    /* End version and print information.            */
  120. } TheDoc;
  121.  
  122.  
  123. The first thing your code does is to read in the version and print
  124. record information.  (AppReadDocument already has sample code to
  125. do this.  Just keep the code.)  You then read in the rest of your
  126. document into the portion of the structure starting after the field
  127. endLocalInfo.  The application-specific portion of this structure
  128. for the MacShell sample is a text handle, followed by two TextEdit
  129. handles.  Not all of this portion needs to be saved to disk.  (In
  130. the MacShell sample, the data for the TextEdit handle is the only
  131. portion saved to disk.)
  132.  
  133. To write out your document, just replace the appropriate code in
  134. the function AppWriteDocument.  It will get called when needed.
  135.  
  136. If you have multiple document types, you can reference the sfType
  137. field to determine which document type you are dealing with.
  138. Whenever a document is created via AppNewDocument or opened via
  139. AppOpenDocument, the OSType is saved in the field sfType.  If there
  140. is custom initialization that needs to occur based on the document
  141. type, then AppInitDocument can reference sfType to determine which
  142. document type is being initialized.
  143.  
  144.  
  145. The final file I/O function that you need is AppDuplicateDocument.
  146. You might not even want this feature in your application.  If not,
  147. then yank it from MacShell.  If you want it, then add the code
  148. necessary to duplicate a document in the function.
  149.  
  150.  
  151.  
  152. All you need at this point to try your application for the first
  153. time is an imaging procedure.  Replace the code in the function
  154. ImageDocument with your own, and you are ready to try compiling
  155. your application.  Given that you removed the sample data area
  156. from the document structure and replaced it with your own, you
  157. will most likely not compile.  Let the compiler find the exceptions
  158. and then fix them.  After this step, you should have a skeleton of
  159. your application that handles file I/O and printing.
  160.  
  161. Once you have a skeleton running, you will wish to modify or replace
  162. the remaining procedure pointers that define the behavior of the
  163. document window.  All of these functions will be found in the file
  164. window2.c
  165.  
  166.  
  167. To find the other areas that you will need to change, see the RoadMap
  168. file.  It has bullet points marking the source files that you need
  169. to be concerned with.
  170.  
  171.  
  172. Another good way to get a global picture of MacShell is to read the
  173. ‘! MacShell.fn.descriptions’ file.  This file lists all of the
  174. functions, just as MacShell.protos does, but it also has a function
  175. description of each and how it is used within MacShell.
  176.  
  177.  
  178.  
  179. This should get you well on your way to using MacShell as a framework
  180. for your application.
  181.  
  182.